Preparation for rst conversion by maiska · Pull Request #1418 · QubesOS/qubes-doc

maiska · 2024-08-11T14:44:27Z

Fixed some issues that were fixable in mardown and listed in #1367.

This pull request should ease up and eliminate a lot of small annonying errors when converting

marmarek · 2025-05-28T14:27:18Z

CI says there is a typo:

The following new unknown spellings were introduced:
    +fromatted
In addition, the following suspicious spellings were eliminated:
    -F1
    -installroot
    -vis
The introduced suspects in context are:
./_doc/developer/services/admin-api.md:221:Fields should be fromatted to `%`-style format string, possibly after

maiska · 2025-05-29T12:48:09Z

@marmarek Thank you for pointing this out, will look at it !

maiska · 2025-06-06T00:02:54Z

developer/general/gsoc.md

@@ -174,45 +174,6 @@ If applicable, links to more information or discussions

 **Mentor**: [Frédéric Pierret](/team/)



removed commented out section. should the information be available in some other form somewhere still?

better to remove it entirely, it's still in the history if someone wants to restore it later, there was certainly a reason to comment, but it's not like it's unrecoverable if you remove it

maiska · 2025-06-06T00:05:50Z

developer/general/gsod.md


-You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
+You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/).



Please have a look at the web archived versions of the reports

they look good enough for a web archive link! No problem for me

maiska · 2025-06-06T00:06:12Z

developer/releases/4_0/release-notes.md

 ----------------------

-* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/index.html)
+* Core management scripts rewrite with better structure and extensibility, [API documentation](https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)


Please have a look at the web archived versions of the documentaion

I'm afraid this archive is useless, there is only an index and no links are indexed by web archive.

I think we can keep the link dev.qubes-os.org because people may want to find the current API documentation after all

I reworded it will push shortly

maiska · 2025-06-06T00:08:34Z

developer/services/qmemman.md


-The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
+The [tmem](https://web.archive.org/web/20210712161104/https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:



webarchive url

content is ok for me

maiska · 2025-06-06T00:09:31Z

developer/system/template-manager.md

 actions such as renaming
 ([#839](https://github.com/QubesOS/qubes-issues/issues/839)), removal
-([#5509](https://github.com/QubesOS/qubes-issues/issues/5509)) and
+([#5509](https://web.archive.org/web/20210526123932/https://github.com/QubesOS/qubes-issues/issues/5509)) and


webarchive url

looks good to me

maiska · 2025-06-06T00:10:54Z

user/advanced-topics/salt.md

 Documentation about using Jinja to directly call Salt functions and get data
 about your system can be found in the official
-[Salt documentation](https://docs.saltproject.io/en/getstarted/config/jinja.html#get-data-using-salt).
+[Salt documentation](https://docs.saltproject.io/salt/user-guide/en/latest/topics/jinja.html).


please review the new link

the new link fits fine IMO

maiska · 2025-06-06T00:11:27Z

user/advanced-topics/standalones-and-hvms.md


 Please see [this
-page](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md)
+page](/doc/templates/windows/windows-qubes-4-1/#windows-as-a-template)


please review the new referal

good for me

maiska · 2025-06-06T00:11:44Z

user/advanced-topics/standalones-and-hvms.md

 Other documents related to HVMs:

- [Windows VMs](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md)
+- [Windows VMs](https://forum.qubes-os.org/search?q=windows%20hvm%20%23guides)


please review the new referal

maiska · 2025-06-06T00:12:03Z

user/downloading-installing-upgrading/install-security.md

 * Untrustworthy firmware.
  (Firmware can be malicious even if the drive is new.
-  Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://srlabs.de/badusb/).
+  Plugging a drive with rewritable firmware into a compromised machine can also [compromise the drive](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil).


please review the new referal

I'm not sure the new link is useful, I find a description of a talk but no recording and no information, did I miss something?

exhcanged the link

maiska · 2025-06-06T00:12:25Z

user/hardware/certified-hardware/certified-hardware.md

 | [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro 2](https://shop.nitrokey.com/shop/nitropc-pro-2-523)                                                                                                      | [Certification details](/doc/certified-hardware/nitropc-pro-2/)             |
 | [Star Labs](https://starlabs.systems/) | [StarBook](https://starlabs.systems/pages/starbook)                                                                                                                    | [Certification details](/doc/certified-hardware/starlabs-starbook/)         |
-| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523)                                                                                                  | [Certification details](/doc/certified-hardware/nitropc-pro/)               |
+| [Nitrokey](https://www.nitrokey.com/)  | [NitroPC Pro](https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523)                                                       | [Certification details](/doc/certified-hardware/nitropc-pro/)               |


please review the new referal as it is also a webarchive

Indeed the old NitroPc Pro page is gone (not sold anymore), but still supported. So the link is okay.

the link itself is fine and can be useful although it's not sold anymore, but we should put a comment or warning that it's not sold anymore and that the link is an archive.

I can imagine someone trying to buy a nitropc from the web archive link 😅

Could that be reworded/commented after this PR is merged @andrewdavidwong what do you think?

maiska · 2025-06-06T00:12:48Z

user/hardware/certified-hardware/nitropc-pro.md

 </div>

-The [NitroPC Pro](https://shop.nitrokey.com/shop/product/nitropc-pro-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.
+The [NitroPC Pro](https://web.archive.org/web/20231027112856/https://shop.nitrokey.com/shop/product/nitropc-pro-523) is [officially certified](/doc/certified-hardware/) for Qubes OS Release 4.


please review the new referal as it is also webarchive

and here too 👍

same comment as previous

maiska · 2025-06-06T00:13:03Z

user/hardware/certified-hardware/nitropc-pro.md

 - Exclusive newsletter
 - Special firmware updates, including early access to updates enhancing privacy, security, performance, and compatibility
- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/main/dug2_dasharo_roadmap.md#dasharo-desktop-roadmap))
+- Early access to new firmware releases for [newly-supported desktop platforms](https://docs.dasharo.com/variants/overview/#desktop) (please see the [roadmap](https://github.com/Dasharo/presentations/blob/main/archive/dug_2/dug2_dasharo_roadmap.md#dasharo-desktop-roadmap))


please review the new referal

I found a commit before the file got renamed/removed, it has working pictures compared to your link

https://github.com/Dasharo/presentations/blob/8f360b3e82108d1e85585c1c324a28a08dd276a5/dug2_dasharo_roadmap.md

maiska · 2025-06-06T00:13:44Z

user/how-to-guides/how-to-organize-your-qubes.md


 - **Two qubes for taxes.** Carol has a [Windows
-  qube](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows.md)
+  qube](/doc/templates/windows/)


please review the new referal

works for me

maiska · 2025-06-06T00:14:32Z

user/security-in-qubes/anti-evil-maid.md

 (The other option is to install AEM to an internal disk.
 However, this carries significant security implications, as explained [here](https://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html).) This presents us with a classic security trade-off: each Qubes user must make a choice between protecting dom0 from a potentially malicious USB drive, on the one hand, and protecting the system from Evil Maid attacks, on the other hand.
-Given the practical feasibility of attacks like [BadUSB](https://srlabs.de/badusb/) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision.
+Given the practical feasibility of attacks like [BadUSB](https://www.blackhat.com/us-14/briefings.html#badusb-on-accessories-that-turn-evil) and revelations regarding pervasive government hardware backdoors, this is no longer a straightforward decision.


please review the new referal

was commented earlier, I don't find this link to be useful, it gives no information except there was a talk about evil USB things, without content to read/watch

exchanged the link

maiska · 2025-06-06T00:14:43Z

user/security-in-qubes/firewall_4.1.md

 If you adopt this model, you should be aware that all traffic will arrive at the `network service qube` appearing to originate from the IP address of `sys-firewall-2`.

-For the VPN service please also look at the [VPN documentation](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md).
+For the VPN service please also look at the [VPN documentation](https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061).


please review the new referal

maiska · 2025-06-06T00:18:03Z

user/troubleshooting/uefi-troubleshooting.md

 ## Installation completes successfully but then system crash/restarts on next boot

-Some Dell systems and probably others have [another bug in UEFI firmware](https://markmail.org/message/amw5336otwhdxi76).
+Some Dell systems and probably others have [another bug in UEFI firmware](https://web.archive.org/web/20170901231026/https://markmail.org/message/amw5336otwhdxi76).


please review the new referal

rapenne-s

From the diff itself, I did not find big issues. Good job @maiska for that huge work, it's impressive.

I did not check the rendering when it was trivial, for biggest changes including indentation rework, I verified it looked correctly.

However, I crawled the documentation on the testing website, following links for a while a bit randomly, I only found a html left-over at the end of https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/migrate-to-4-1.html

rapenne-s · 2025-06-30T16:44:46Z

developer/building/qubes-builder-v2.md

 2. Installing dependencies

-   If you want to use an app qube for developing, install dependencies in the template.
+   - If you want to use an app qube for developing, install dependencies in the template.


it looks bad, I'm not sure if the - was intentional here?
I'm not sure it's needed to have a -, there is a paragraph a bit after the 2. and it looks great

i suppose i did this because of some conversion/formatting issues specifically for lists in markdown and rst :)

rapenne-s · 2025-06-30T17:09:16Z

developer/general/gsoc.md

@@ -174,45 +174,6 @@ If applicable, links to more information or discussions

 **Mentor**: [Frédéric Pierret](/team/)



better to remove it entirely, it's still in the history if someone wants to restore it later, there was certainly a reason to comment, but it's not like it's unrecoverable if you remove it

rapenne-s · 2025-06-30T17:12:45Z

developer/general/gsod.md


-You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
+You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/).



they look good enough for a web archive link! No problem for me

rapenne-s · 2025-06-30T17:16:12Z

developer/releases/4_0/release-notes.md

 ----------------------

-* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/index.html)
+* Core management scripts rewrite with better structure and extensibility, [API documentation](https://web.archive.org/web/20230128102821/https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/)


I'm afraid this archive is useless, there is only an index and no links are indexed by web archive.

I think we can keep the link dev.qubes-os.org because people may want to find the current API documentation after all

rapenne-s · 2025-06-30T17:23:04Z

developer/services/qmemman.md


-The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
+The [tmem](https://web.archive.org/web/20210712161104/https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:



content is ok for me

rapenne-s · 2025-06-30T18:42:02Z

user/templates/fedora/fedora-upgrade.md

-        `
-        At least X MB more space needed on the / filesystem.
-        `
+     - `dnf` may complain: `At least X MB more space needed on the / filesystem.`


Suggested change

- `dnf` may complain: `At least X MB more space needed on the / filesystem.`

- `dnf` may error with the text `At least X MB more space needed on the / filesystem.`

rapenne-s · 2025-06-30T18:48:18Z

user/templates/windows/qubes-windows-tools-4-1.md

 For further information on usage of disposables, see [How to use disposables](/doc/how-to-use-disposables/).

-**Caution:** *If a Windows-based disposable is used from another qube via the Open/Edit in DisposableVM command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down  manually.*
+**Caution:** *If a Windows-based disposable is used from another qube via the* `Open/Edit in DisposableVM` *command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down  manually.*


I don't have the context, not sure to understand the problem, but it looks fine for me here

rapenne-s · 2025-06-30T18:53:06Z

user/troubleshooting/installation-troubleshooting.md

-    ```
-    nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
-    ```
+  ```bash


it's not bash

i suppose i did this because of some conversion/formatting issues

rapenne-s · 2025-06-30T18:53:27Z

user/troubleshooting/installation-troubleshooting.md

-    ```   
-    noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img
-    ```
+  ```bash   


i suppose i did this because of some conversion/formatting issues

rapenne-s · 2025-06-30T18:54:06Z

user/troubleshooting/uefi-troubleshooting.md

 ## Installation completes successfully but then system crash/restarts on next boot

-Some Dell systems and probably others have [another bug in UEFI firmware](https://markmail.org/message/amw5336otwhdxi76).
+Some Dell systems and probably others have [another bug in UEFI firmware](https://web.archive.org/web/20170901231026/https://markmail.org/message/amw5336otwhdxi76).


maiska · 2025-07-01T07:46:25Z

From the diff itself, I did not find big issues. Good job @maiska for that huge work, it's impressive.

I did not check the rendering when it was trivial, for biggest changes including indentation rework, I verified it looked correctly.

However, I crawled the documentation on the testing website, following links for a while a bit randomly, I only found a html left-over at the end of https://current-qubes-docrtd.readthedocs.io/en/rtd-deploy-pr/user/templates/windows/migrate-to-4-1.html

Thank you! Now it should be fixed

user/downloading-installing-upgrading/install-security.md

marmarek · 2025-07-03T17:02:08Z

Is it all okay now? @maiska please merge when ready so I can do the conversion

maiska · 2025-07-03T19:16:25Z

Is it all okay now? @maiska please merge when ready so I can do the conversion

all right, i was waiting for the final go, though undefined what this looked like :)
I did some final changes. To be safe though @rapenne-s would you confirm that they are ok.
4554eef
and a fix mistabbed file:
e3db139

rapenne-s · 2025-07-03T19:55:30Z

All good for me :)

maiska added 30 commits June 1, 2024 13:08

add newline for better rst conversion

be4bbda

add newlines for better rst conversion

d04ee19

Remove space for better rst conversion

0f1268e

add newline for better rst conversion

20972f2

add new line for better rst conv

6cf2fd5

new lines rst conv

3ef2cd7

new line rst conv

3dcfa93

newline rst conv

6b2ad28

better comv for rst prep

5050b8d

better conv for rst

ee6a768

better conv 4 rst

607d525

better formatting for rst conversion

c78d562

formatting for better rst conversion

2346dac

better formatting for rst conv

326adab

better conv for rst

a1e5c64

better conv for rst

90ed11a

for better conv to rst

93f851d

preparation rst conversion

32c32e6

preparation rst conversion

0a94a1f

preparation rst conversion

38cfff0

preparation rst conversion

b7c6ff3

preparation rst ocnversion

8fd6045

preparation rst ocnversion

da97d63

preparation rst ocnversion

7c2b1a4

preparation rst ocnversion

ae14469

prepare conversion to rst

a60dc3a

Merge branch 'QubesOS:main' into main

5941ae9

Merge branch 'QubesOS:main' into main

230c80f

preparation rst conversion

f9c3715

preparation conversion rst

3e93bd5

maiska added 2 commits June 3, 2025 13:51

pre-final fixes

524928b

update from upstream

7eaecbd

maiska commented Jun 6, 2025

View reviewed changes

admin-api reset to upstream

823c5f3

rapenne-s requested changes Jun 30, 2025

View reviewed changes

exchanged webarchive links, minor wording

4554eef

marmarek reviewed Jul 1, 2025

View reviewed changes

user/downloading-installing-upgrading/install-security.md Outdated Show resolved Hide resolved

fixed a tab

e3db139

maiska merged commit e3db139 into QubesOS:main Jul 3, 2025
1 check failed

		@@ -174,45 +174,6 @@ If applicable, links to more information or discussions

		Mentor: [Frédéric Pierret](/team/)


		You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://refre.ch/report-qubesos/).
		You can view the project we had in 2019 in the [2019 GSoD archive](https://developers.google.com/season-of-docs/docs/2019/participants/project-qubes) and the [2019 writer's report](https://web.archive.org/web/20200928002746/https://refre.ch/report-qubesos/).


		The [tmem](https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:
		The [tmem](https://web.archive.org/web/20210712161104/https://oss.oracle.com/projects/tmem/) project provides a "pseudo-RAM" that is assigned on per-need basis. However this solution has some disadvantages:

	- `dnf` may complain: `At least X MB more space needed on the / filesystem.`
	- `dnf` may error with the text `At least X MB more space needed on the / filesystem.`

Uh oh!

Conversation

maiska commented Aug 11, 2024

Uh oh!

marmarek commented May 28, 2025

Uh oh!

maiska commented May 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!